Agent Infrastructure.md

Dynaplex Agent Infrastructure

The agent infrastructure is not an add-on to Dynaplex—it is a fundamental part of the paradigm. This document describes the tools and systems that enable multi-agent development workflows.

Overview

The Dynaplex agent infrastructure consists of:

Component	Purpose
Agent Teams	Claude Code native multi-agent orchestration
Linear	Issue tracking via Linear MCP server tools
Identity System	File-based agent identity management via `.dplx/config.json`
Cortex Web UI	Dashboard for identity and documentation browsing

Together, these components enable a development model where multiple agents work in parallel, coordinate their efforts, and maintain context across sessions.

Agent Teams (Primary Coordination)

Claude Code Agent Teams is the primary mechanism for multi-agent coordination. A lead agent can spawn teammates who work within the same worktree.

How It Works

A lead agent starts a session via dplx session new
The lead is placed in a sibling worktree with Agent Teams enabled
The lead can spawn teammates to work on parallel tasks
Teammates claim non-lead identities via state files

Lead vs Teammate

Role	Identity	Worktree	Spawned By
Lead	`team_lead: true` in config	Own sibling worktree	`dplx session new`
Teammate	`team_lead: false` in config	Shares lead's worktree	Lead agent via Agent Teams

Identity System

Configuration

Agent identities are defined in .dplx/config.json:

{
  "identities": [
    { "name": "Bliss", "presents_as": "female", "team_lead": true },
    { "name": "Andrew", "presents_as": "male", "team_lead": false }
  ],
  "team_names": ["Terminus", "Trantor", "Aurora"]
}

Status Tracking

Identity status is determined entirely by filesystem state:

Lead "in use": Sibling worktree directory ../acsis-core-{name}-worktree/ exists
Teammate active: State file .claude/state/teammates/{name} exists in lead's worktree
Agent name: Stored in .claude/state/agent_name within each worktree

Cortex CLI

dotnet dplx identity list       # Show all identities with status
dotnet dplx identity show <n>   # Show identity detail
dotnet dplx identity toggle <n> # Toggle team_lead status

Linear: Issue Tracking

Linear is the project's issue tracking system, accessed via Linear MCP server tools.

Key Capabilities

Dependency-aware task management
Priority tracking (P0-P4)
Cross-session persistence
Referenced in commit messages (Refs: SWE-xxx)

Git Worktrees

Each lead agent works in an isolated sibling worktree:

portfolio/
├── acsis-core/                      # Main repo (not used by agents)
├── acsis-core-bliss-worktree/       # Agent Bliss's workspace
├── acsis-core-daneel-worktree/      # Agent Daneel's workspace
└── acsis-core-hari-worktree/        # Agent Hari's workspace

Isolation Guarantees

File isolation: Changes in one worktree don't affect others
Build isolation: Each worktree has its own bin/ and obj/
Database isolation: Each AppHost gets its own PostgreSQL container
Process isolation: Each agent runs their own Aspire AppHost

Worktree Rules

Never modify another agent's worktree directly
Commit and push changes to make them available to others
Cleanup when done to release resources

Session Management

Starting a Session

dplx session new              # Auto-select available lead
dplx session new Bliss        # Use specific agent
dplx session list             # Show active/available sessions

The command creates the sibling worktree, restores packages, configures git identity, and launches Claude Code with Agent Teams enabled.

Ending a Session

dplx session clean <agent-name>          # Normal cleanup
dplx session clean <agent-name> --force  # Force cleanup
dplx session clean                       # Clean ALL active sessions

The Session Loop

A typical agent workflow:

Start: dplx session new assigns identity, creates worktree
Find work: Check Linear for available issues
Coordinate: Spawn teammates via Agent Teams for parallel work
Complete work: Commit, push, close issues
Cleanup: dplx session clean tears down worktree

Cortex Web UI

The Cortex web UI (dotnet dplx serve) provides:

Dashboard: Overview of active agents
Identity: View and manage all agent identities with team_lead toggle
Docs: Browse repository documentation (ADRs, tutorials, how-to guides)

Integration with Architecture

The agent infrastructure reinforces the architecture:

Architecture Pattern	Agent Infrastructure Support
Component isolation	Worktree isolation matches service boundaries
Type-safe contracts	Linear tracks contract changes
Explicit dependencies	Linear dependency graph mirrors service graph
Parallel development	Agent Teams enables concurrent work

This is the Dynaplex philosophy in action: architecture and tooling are not separate concerns.

Agents are not tools that use the system—they are participants in the system. The infrastructure enables this participation.

Documentation